/*
 * Copyright (c) 2007, TopCoder, Inc. All rights reserved.
 */

using System;
using System.Collections.Generic;

namespace TopCoder.Util.Calendar.Entry
{
    /// <summary>
    /// <para>This interface defines the contract for all calendar entry data sources.</para>
    /// <para>
    /// It provides various search functionality such as search by id, by type, by description(partially match,
    /// which means the given description will be a substring of the description of any entry in the returned list)
    /// and by date range.
    /// </para>
    /// </summary>
    /// <remarks>
    /// Thread Safety: Implementations of this interface must be thread safe.
    /// </remarks>
    ///
    /// <author>snower, fuyun</author>
    /// <version>1.0</version>
    /// <copyright>Copyright (c) 2007, TopCoder, Inc. All rights reserved.</copyright>
    public interface ICalendarEntryDataSource
    {
        /// <summary>
        /// Finds all calendar entries from the data source layer. If no entry exists, an empty list
        /// will be returned.
        /// </summary>
        /// <returns>all calendar entries stored in the data source or an empty list if no entry exists.</returns>
        /// <exception cref="CalendarEntryDataSourceException">
        /// if any errors occur in the data source layer.
        /// </exception>
        IList<BaseCalendarEntry> FindAllEntries();

        /// <summary>
        /// Finds the calendar entry with the given id, if not such entry exists, null will be returned.
        /// </summary>
        /// <param name="id">the id of the desired calendar entry.</param>
        /// <returns>the calendar entry with the given id or null if no such entry exists.</returns>
        /// <exception cref="CalendarEntryDataSourceException">
        /// if any errors occur in the data source layer.
        /// </exception>
        BaseCalendarEntry FindEntryById(int id);

        /// <summary>
        /// Finds all calendar entries with the given type, if no such records exists, an empty list will be returned.
        /// </summary>
        /// <param name="type">the type by which to search calendar entries.</param>
        /// <returns>all calendar entries with the given type or an empty list if no such entry exists.</returns>
        /// <exception cref="ArgumentNullException">
        /// if type argument is null.
        /// </exception>
        /// <exception cref="CalendarEntryDataSourceException">
        /// if any errors occur in the data source layer.
        /// </exception>
        IList<BaseCalendarEntry> FindEntriesByType(CalendarEntryType type);

        /// <summary>
        /// <para>
        /// Finds all calendar entries whose description partially matches the given description. If no such entry
        /// exists, an empty list will be returned.
        /// </para>
        /// <para>
        /// Partially match the given description is a substring of the description of any desired entry.
        /// </para>
        /// </summary>
        /// <param name="description">the description by which to search calendar entries.</param>
        /// <returns>
        /// all calendar entries whose description partially matches the given description or an empty list
        /// if no such entry exists.
        /// </returns>
        /// <exception cref="ArgumentNullException">
        /// if the description argument is null.
        /// </exception>
        /// <exception cref="ArgumentException">
        /// if description argument is an empty string.
        /// </exception>
        /// <exception cref="CalendarEntryDataSourceException">
        /// if any errors occur in the data source layer.
        /// </exception>
        IList<BaseCalendarEntry> FindEntriesByDescription(string description);

        /// <summary>
        /// Finds all calendar entries within the given date range(inclusive), if no such entry exists,
        /// an empty list will be returned.
        /// </summary>
        /// <param name="startDate">the start date of the date range by which to search calendar entries.</param>
        /// <param name="endDate">the end date of the date range by which to search calendar entries.</param>
        /// <returns>
        /// all calendar entries within the given date range or an empty list if no such entry exists.
        /// </returns>
        /// <exception cref="ArgumentException">
        /// if endDate is before startDate.
        /// </exception>
        /// <exception cref="CalendarEntryDataSourceException">
        /// if any errors occur in the data source layer.
        /// </exception>
        IList<BaseCalendarEntry> FindEntriesByDateRange(DateTime startDate, DateTime endDate);

        /// <summary>
        /// Finds the calendar entry type with the given id, if no such entry type exists, null will be returned.
        /// </summary>
        /// <param name="typeId">the id of the desired calendar entry type.</param>
        /// <returns>the desired calendar entry type or null if no such type exists.</returns>
        /// <exception cref="CalendarEntryDataSourceException">
        /// if any errors occur in the data source layer.
        /// </exception>
        CalendarEntryType FindEntryTypeById(int typeId);

        /// <summary>
        /// <para>
        /// Finds all calendar entry types whose description partially matches the given description.
        /// If no such entry type exists, an empty list will be returned.
        /// </para>
        /// <para>Partially match the given description is a substring of the description of any desired entry type.
        /// </para>
        /// </summary>
        /// <param name="description">the description used to search calendar entry types.</param>
        /// <returns>
        /// all calendar entry types whose description partially matches the given description or an
        /// empty list if no such entry type exists.
        /// </returns>
        /// <exception cref="ArgumentNullException">
        /// if the description argument is null.
        /// </exception>
        /// <exception cref="ArgumentException">
        /// if description argument is an empty string.
        /// </exception>
        /// <exception cref="CalendarEntryDataSourceException">
        /// if any errors occur in the data source layer.
        /// </exception>
        IList<CalendarEntryType> FindEntryTypesByDescription(string description);
    }
}